feat(ootle-wasm): expose create_transfer_statement for spending PayTo::Conditions outputs - #2431

Reviewed at a2648313bdf27f4af0979e031837f84f39c87e52. The wiring itself is correct: the u64/JSON-string ABI matches the rest of lib.rs, the Vec/iter() shapes satisfy create_transfer_statement's ExactSizeIterator + Clone bounds, only the four intended files change (no lockfile/generated churn), and no existing export is touched.

What blocks is the claim the PR is built on, and the test that is supposed to back it up.

Blocking

1. "Required whenever a script-path input is spent" is not what the engine does.

crates/ootle_wasm/wasm/src/lib.rs:369 and crates/ootle_wasm/core/src/stealth/transfer.rs:22 both ship the assertion that this is "the only correct way to spend a PayTo::Conditions (ScriptPath) stealth output", and the PR description justifies the design with "covenant_claims — the balance-integrity proof required whenever a script-path input is spent".

Covenant claims are consumed in exactly one place: SpendScriptExecution::covenant_balanced (crates/engine/src/runtime/spend_script_execution.rs:107), reached only from Covenant::BalancePreserved (crates/engine/src/runtime/impl.rs:961) or a template calling SpendContext::covenant_balanced (crates/engine/src/runtime/impl.rs:3795). A revealed leaf that carries neither — a HashLock, an AfterEpoch refund, an AccessRule — is evaluated without any claim ever being looked at. Note that this is precisely the fixture in this PR's own script-path test (HashLock + AfterEpoch), and precisely the HTLC claim/refund case buildStealthInputsStatementFromInputs documents itself for at lib.rs:327-331.

So for the majority of script paths the sibling export is not a balance-integrity gap, and these docs tell an npm consumer it is. Please restate as what's true: the claim is required when the spend path enforces value conservation (Covenant::BalancePreserved, or a template function that checks it), and this export is the way to get one. Same correction in the PR description, since it is the stated justification for the approach.

2. The script-path test doesn't test the covenant claim.

transfer.rs:126 asserts covenant_claims.len() == 1 and then calls validate_stealth_transfer. tari_engine_types::stealth::validate_transfer never reads covenant_claims — not in basic_validations (crates/engine_types/src/stealth/transfer.rs:173) and not in the body (:61-171). It verifies the outputs statement, the range proof and the transfer-level balance proof, nothing else. So the PR's testing claim that the statement "passes validate_stealth_transfer — the same validation the engine performs" does not hold for the one field this PR exists to populate: the claim's partition_input_index, revealed_amount and signature are all unasserted, and a claim signed over the wrong commitment set would pass this test unchanged.

tari_engine_types::crypto::validate_covenant_balance_proof (crates/engine_types/src/crypto/covenant.rs:27) is public and already a dependency of this crate — assert against it with the partition reconstructed the way covenant_balanced does (spend_script_execution.rs:120-140). Building the fixture with a Covenant::BalancePreserved leaf would also make the produced claim the thing the engine would actually evaluate, rather than an inert one.

Non-blocking

3. "witness":"KeyPath" is rejected here but documented as valid next door. types.rs:150-159 errors on any (Some, None), including the key-path unit variant. lib.rs:331 and inputs.rs:64 both tell callers that "witness":"KeyPath" is the explicit spelling of a key-path input, so someone mixing paths in one buildStealthTransferStatement call — which the new doc encourages — gets an error for JSON the neighbouring export accepts.

Matching on the variant rather than on is_some() fixes that and closes the inverse hole in the same move: today witness: "KeyPath" + a condition_root takes the (Some, Some) branch and builds a StealthInputWitness with a key-path witness and a root, which yields a claim the engine can never match (covenant_balanced keys the partition off script-path inputs only) — a statement that fails at execution with nothing signalling why locally.

4. StealthInputWitnessJson has no deny_unknown_fields (types.rs:132-141). Both new fields default, so a mis-nested merge of buildScriptPathWitness's result (e.g. leaving it under script_path) deserializes silently as a key-path input. It does fail later, but as an authorisation error at spend time rather than a JSON-shape error at build time — worth catching here given the shape is a hand-merge of two call results.

5. KeyAndScript outputs partition differently on the two sides. generate_covenant_claims filters outputs by o.auth.condition_root() == Some(&root) (crates/wallet/crypto/src/stealth.rs:253), which is Some for KeyAndScript (crates/template_lib_types/src/stealth/unspent_output.rs:88). The engine uses is_locked_under (crates/template_lib_types/src/stealth/spend_context.rs:47), which deliberately excludes KeyAndScript. Pre-existing in wallet crypto and today unreachable from wasm, because pay_to_output_authorization only ever emits Key or Script — but this export deserializes the output's auth straight from caller JSON, so a hand-written KeyAndScript output now reaches it and produces a claim signed over a different commitment set than the engine reconstructs. Either fix the filter upstream or reject KeyAndScript outputs here.

Nits

6. The doc block is duplicated near-verbatim across transfer.rs:12-30 and lib.rs:362-378, and both are written as an argument against the sibling API ("not a cosmetic one", bolded "only correct way") — that's PR/commit rationale rather than what a reader of the function needs. inputs.rs:60-64's single "Unlike build_stealth_inputs_statement, which only ever builds key-path inputs…" is the level this repo uses.

7. key_path_only_round_trips_through_validation (transfer.rs:104) is validate::tests::validates_a_well_formed_transfer (validate.rs:47) with a JSON hop added. Fine to keep if the JSON hop is the point, but it isn't new coverage of create_transfer_statement.

8. Dropping the untagged Flat variant is a breaking change to a pub re-export (stealth/mod.rs:18) of ootle-wasm-core, which is a published crate (scripts/publish_crates.py:58). I checked: no wasm export accepted it, and nothing in-tree or in any JS/TS consumer constructs the flat shape, so the change is safe — but it belongs in the commit message rather than going unmentioned.

Re-reviewed at a31a1737bfa9ed9e1467b2fb13831646752ea293. Both blocking items are resolved, and 3, 4 and 5 are addressed too. Checked, not just taken on faith:

• Scope of the claim — the doc now ties it to Covenant::BalancePreserved (or a TemplateFunction calling covenant_balanced) and says outright that the separate-calls path stays valid for hashlock/timelock/access-rule leaves. That matches impl.rs:961 and spend_script_execution.rs:107.
• Test — the fixture is a real BalancePreserved(0) leaf with the output re-locked under Script(condition_root), verified through validate_covenant_balance_proof with the partition reconstructed the engine's way, plus a negative control on a tampered revealed_amount. That's the assertion that was missing. Hash32 is serde-transparent hex and PedersenCommitmentBytes is Copy, so the new test code lines up.
• Witness matching — matching on the variant handles the "KeyPath" spelling and closes KeyPath + condition_root and ScriptPath without a root, each with a test.
• KeyAndScript partition — fixing it at the source in wallet/crypto/src/stealth.rs:253 is the right call. The two existing engine tests that build KeyAndScript outputs (spend_script.rs:382, :1064) gate on OutputPreservesCondition, not BalancePreserved, so their rejection reasons are unaffected, and a wider revealed_amount can't newly trip the checked_sub guard (a partition always has at least one input).

Two leftovers, neither blocking:

• The description still says "Scope: Wasm bindings only. No change to ..." but crates/wallet/crypto is now in the diff. Worth correcting, since that crate change alters claim generation for every existing caller of create_transfer_statement, not just the new wasm export.
• wasm/src/lib.rs:366 sends a reader to "buildStealthTransferStatement in ootle-wasm-core" — that's this function's own JS name, so the pointer doesn't resolve. build_stealth_transfer_statement is the Rust name over there.

Not approving yet only because CI hasn't run: the CI and PR workflow runs for this head are sitting in action_required (fork PR needing a maintainer to authorize the run), so the two checks reporting green are just the always-on ones. I'll approve once the suite actually runs clean — someone with write access needs to release the workflow runs.

Thank you 🚀